<!-- HTML header for doxygen 1.8.3.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>AngelScript: Debugging scripts</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="test/javascript" src="touch.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('doc_debug.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Debugging scripts </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>AngelScript offers a rich interface to support the debugging of scripts. It is easy to build an embedded debugger that can set break points, inspect/manipulate variables in functions, visualize the call stack, etc.</p>
<p>Observe that the CDebugMgr class used in the examples below doesn't exist. It is only used as an abstraction to avoid having to write fictional debug routines.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="doc_addon_debugger.html">Debugger</a> for a standard implementation</dd></dl>
<h1><a class="anchor" id="doc_debug_1"></a>
Setting line breaks</h1>
<p>In order to break at a specified line in the code the debugger can set the line callback function in the script context. The VM will then invoke the callback for each statement executed, allowing the debugger to decide whether to proceed to the next statement or not.</p>
<div class="fragment"><div class="line"><span class="comment">// An example line callback</span></div>
<div class="line"><span class="keywordtype">void</span> DebugLineCallback(<a class="code" href="classas_i_script_context.html" title="The interface to the virtual machine.">asIScriptContext</a> *ctx, CDebugMgr *dbg)</div>
<div class="line">{</div>
<div class="line">  <span class="comment">// Determine if we have reached a break point</span></div>
<div class="line">  <span class="keyword">const</span> <span class="keywordtype">char</span> *scriptSection;</div>
<div class="line">  <span class="keywordtype">int</span> line = ctx-&gt;<a class="code" href="classas_i_script_context.html#adf82981def59c6ec5dd9f74f034be2af" title="Returns the line number at the specified callstack level.">GetLineNumber</a>(0, 0, &amp;scriptSection);</div>
<div class="line">  asIScriptFunction *<span class="keyword">function</span> = ctx-&gt;<a class="code" href="classas_i_script_context.html#a1c101300447f2909e5d188409a7180f6" title="Returns the function at the specified callstack level.">GetFunction</a>();</div>
<div class="line"></div>
<div class="line">  <span class="comment">// Now let the debugger check if a breakpoint has been set here</span></div>
<div class="line">  <span class="keywordflow">if</span>( dbg-&gt;IsBreakpoint(scriptSection, line, <span class="keyword">function</span>) )</div>
<div class="line">  {</div>
<div class="line">    <span class="comment">// A break point has been reached so the execution of the script should be suspended</span></div>
<div class="line">    ctx-&gt;<a class="code" href="classas_i_script_context.html#ad4ac8be3586c46069b5870e40c86544a" title="Suspends the execution, which can then be resumed by calling Execute again.">Suspend</a>();</div>
<div class="line">  }</div>
<div class="line">}</div>
</div><!-- fragment --><p>The line callback is set on the context with the following call:</p>
<div class="fragment"><div class="line"><span class="comment">// Set the line callback with the address of the debug manager as parameter</span></div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#ae2747f643bf9a07364f922c460ef57dd" title="Sets a line callback function. The function will be called for each executed script statement...">SetLineCallback</a>(<a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(DebugLineCallback), dbg, <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4" title="A cdecl function.">asCALL_CDECL</a>);</div>
</div><!-- fragment --><p>When the line callback suspends the execution the context's <a class="el" href="classas_i_script_context.html#a8e52894432737acac2e1a422e496bf84">Execute</a> function will return with the code <a class="el" href="angelscript_8h.html#a867f14b4137dd4602fda1e616b217a69a7b5644be315c46f2fa44f032731242c7">asEXECUTION_SUSPENDED</a>. The application can then go into a special message loop where the debug routines can be handled, e.g. to <a class="el" href="doc_debug.html#doc_debug_2">view the call stack</a>, <a class="el" href="doc_debug.html#doc_debug_3">examine variables</a>, etc. Once the execution should continue, simply call the Execute method again to resume it.</p>
<p>An alternative to suspending the script execution might be to start the message loop directly within the line callback, in which case resuming the execution is done simply by returning from the line callback function. Which is the easiest to implement depends on how you have implemented your application.</p>
<h1><a class="anchor" id="doc_debug_2"></a>
Viewing the call stack</h1>
<p>The <a class="el" href="classas_i_script_context.html" title="The interface to the virtual machine.">asIScriptContext</a> exposes the call stack for viewing purposes, so that you can easily track the origin of calls. It is also possible to <a class="el" href="doc_debug.html#doc_debug_3">print the value of variables</a> at each level in the callstack.</p>
<p>Here's an example of how the entire call stack can be printed:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> PrintCallstack(<a class="code" href="classas_i_script_context.html" title="The interface to the virtual machine.">asIScriptContext</a> *ctx)</div>
<div class="line">{</div>
<div class="line">  <span class="comment">// Show the call stack</span></div>
<div class="line">  <span class="keywordflow">for</span>( <a class="code" href="angelscript_8h.html#ac8186f029686800b7ce36bde4a55c815" title="32 bit unsigned integer">asUINT</a> n = 0; n &lt; ctx-&gt;<a class="code" href="classas_i_script_context.html#aab359abc4563a8439338bfd655824bd7" title="Returns the size of the callstack, i.e. the number of functions that have yet to complete.">GetCallstackSize</a>(); n++ )</div>
<div class="line">  {</div>
<div class="line">    asIScriptFunction *func;</div>
<div class="line">    <span class="keyword">const</span> <span class="keywordtype">char</span> *scriptSection;</div>
<div class="line">    <span class="keywordtype">int</span> line, column;</div>
<div class="line">    func = ctx-&gt;<a class="code" href="classas_i_script_context.html#a1c101300447f2909e5d188409a7180f6" title="Returns the function at the specified callstack level.">GetFunction</a>(n);</div>
<div class="line">    line = ctx-&gt;<a class="code" href="classas_i_script_context.html#adf82981def59c6ec5dd9f74f034be2af" title="Returns the line number at the specified callstack level.">GetLineNumber</a>(n, &amp;column, &amp;scriptSection);</div>
<div class="line">    printf(<span class="stringliteral">&quot;%s:%s:%d,%d\n&quot;</span>, scriptSection,</div>
<div class="line">                            func-&gt;<a class="code" href="classas_i_script_function.html#a2fb021b09ae0e7e87f8fa4fdfd39df83" title="Returns the function declaration.">GetDeclaration</a>(),</div>
<div class="line">                            line, column);</div>
<div class="line">  }</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="doc_debug_3"></a>
Inspecting variables</h1>
<p>Through the context interface it is possible to inspect and even modify the value of the local variables on the stack. This can be done for each level in the call stack, and not just the current function that is being executed.</p>
<p>Here is an example for how the variables may be printed:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> PrintVariables(<a class="code" href="classas_i_script_context.html" title="The interface to the virtual machine.">asIScriptContext</a> *ctx, <a class="code" href="angelscript_8h.html#ac8186f029686800b7ce36bde4a55c815" title="32 bit unsigned integer">asUINT</a> stackLevel)</div>
<div class="line">{</div>
<div class="line">  <a class="code" href="classas_i_script_engine.html" title="The engine interface.">asIScriptEngine</a> *engine = ctx-&gt;<a class="code" href="classas_i_script_context.html#a07f12016c5435aec5b63449abb6e4d8d" title="Returns a pointer to the engine.">GetEngine</a>();</div>
<div class="line"></div>
<div class="line">  <span class="comment">// First print the this pointer if this is a class method</span></div>
<div class="line">  <span class="keywordtype">int</span> typeId = ctx-&gt;<a class="code" href="classas_i_script_context.html#a404681f8950c1ebd9382d30ef1ed3b89" title="Returns the type id of the object, if a class method is being executed.">GetThisTypeId</a>(stackLevel);</div>
<div class="line">  <span class="keywordtype">void</span> *varPointer = ctx-&gt;<a class="code" href="classas_i_script_context.html#a4f6761a7a0c872dda681d8e180830ff9" title="Returns a pointer to the object, if a class method is being executed.">GetThisPointer</a>(stackLevel);</div>
<div class="line">  <span class="keywordflow">if</span>( typeId )</div>
<div class="line">  {</div>
<div class="line">    printf(<span class="stringliteral">&quot; this = 0x%x\n&quot;</span>, varPointer);</div>
<div class="line">  }</div>
<div class="line"></div>
<div class="line">  <span class="comment">// Print the value of each variable, including parameters</span></div>
<div class="line">  <span class="keywordtype">int</span> numVars = ctx-&gt;<a class="code" href="classas_i_script_context.html#a3d735c6c7c5a166302cc4ba8ea38e3e8" title="Returns the number of local variables at the specified callstack level.">GetVarCount</a>(stackLevel);</div>
<div class="line">  <span class="keywordflow">for</span>( <span class="keywordtype">int</span> n = 0; n &lt; numVars; n++ )</div>
<div class="line">  {</div>
<div class="line">    <span class="keywordtype">int</span> typeId = ctx-&gt;<a class="code" href="classas_i_script_context.html#a8684e1931e54dbfe53da763fc334413d" title="Returns the type id of a local variable at the specified callstack level.">GetVarTypeId</a>(n, stackLevel); </div>
<div class="line">    <span class="keywordtype">void</span> *varPointer = ctx-&gt;<a class="code" href="classas_i_script_context.html#acc916505d79de321a2ab2b46b1c61fb7" title="Returns a pointer to a local variable at the specified callstack level.">GetAddressOfVar</a>(n, stackLevel);</div>
<div class="line">    <span class="keywordflow">if</span>( typeId == <a class="code" href="angelscript_8h.html#ae8c3a67a97321be53181e9ed396ad83aabcc8e086d59505f6ba18ea85e72afc33" title="The type id for int.">asTYPEID_INT32</a> )</div>
<div class="line">    {</div>
<div class="line">      printf(<span class="stringliteral">&quot; %s = %d\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#ae3419d239a51d702870b1ab8ee1b7140" title="Returns the declaration of a local variable at the specified callstack level.">GetVarDeclaration</a>(n, stackLevel), *(<span class="keywordtype">int</span>*)varPointer);</div>
<div class="line">    }</div>
<div class="line">    <span class="keywordflow">else</span> <span class="keywordflow">if</span>( typeId == <a class="code" href="angelscript_8h.html#ae8c3a67a97321be53181e9ed396ad83aa43ec6e15e840ebf165070c2ebe9c954d" title="The type id for float.">asTYPEID_FLOAT</a> )</div>
<div class="line">    {</div>
<div class="line">      printf(<span class="stringliteral">&quot; %s = %f\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#ae3419d239a51d702870b1ab8ee1b7140" title="Returns the declaration of a local variable at the specified callstack level.">GetVarDeclaration</a>(n, stackLevel), *(<span class="keywordtype">float</span>*)varPointer);</div>
<div class="line">    }</div>
<div class="line">    <span class="keywordflow">else</span> <span class="keywordflow">if</span>( typeId &amp; <a class="code" href="angelscript_8h.html#ae8c3a67a97321be53181e9ed396ad83aa29f9a7c07904452b512431b7b4b5b6e4" title="The bit that shows if the type is a script class.">asTYPEID_SCRIPTOBJECT</a> )</div>
<div class="line">    {</div>
<div class="line">      <a class="code" href="classas_i_script_object.html" title="The interface for an instance of a script object.">asIScriptObject</a> *obj = (<a class="code" href="classas_i_script_object.html" title="The interface for an instance of a script object.">asIScriptObject</a>*)varPointer;</div>
<div class="line">      <span class="keywordflow">if</span>( obj )</div>
<div class="line">        printf(<span class="stringliteral">&quot; %s = {...}\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#ae3419d239a51d702870b1ab8ee1b7140" title="Returns the declaration of a local variable at the specified callstack level.">GetVarDeclaration</a>(n, stackLevel));</div>
<div class="line">      <span class="keywordflow">else</span></div>
<div class="line">        printf(<span class="stringliteral">&quot; %s = &lt;null&gt;\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#ae3419d239a51d702870b1ab8ee1b7140" title="Returns the declaration of a local variable at the specified callstack level.">GetVarDeclaration</a>(n, stackLevel));</div>
<div class="line">    }</div>
<div class="line">    <span class="keywordflow">else</span> <span class="keywordflow">if</span>( typeId == engine-&gt;<a class="code" href="classas_i_script_engine.html#ad1f6fecb0f53fd7966736b01f65c3dcb" title="Returns a type id by declaration.">GetTypeIdByDecl</a>(<span class="stringliteral">&quot;string&quot;</span>) )</div>
<div class="line">    {</div>
<div class="line">      <span class="keywordtype">string</span> *str = (<span class="keywordtype">string</span>*)varPointer;</div>
<div class="line">      <span class="keywordflow">if</span>( str )</div>
<div class="line">        printf(<span class="stringliteral">&quot; %s = &#39;%s&#39;\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#ae3419d239a51d702870b1ab8ee1b7140" title="Returns the declaration of a local variable at the specified callstack level.">GetVarDeclaration</a>(n, stackLevel), str-&gt;c_str());</div>
<div class="line">      <span class="keywordflow">else</span></div>
<div class="line">        printf(<span class="stringliteral">&quot; %s = &lt;null&gt;\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#ae3419d239a51d702870b1ab8ee1b7140" title="Returns the declaration of a local variable at the specified callstack level.">GetVarDeclaration</a>(n, stackLevel));</div>
<div class="line">    }</div>
<div class="line">    <span class="keywordflow">else</span></div>
<div class="line">    {</div>
<div class="line">      printf(<span class="stringliteral">&quot; %s = {...}\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#ae3419d239a51d702870b1ab8ee1b7140" title="Returns the declaration of a local variable at the specified callstack level.">GetVarDeclaration</a>(n, stackLevel));</div>
<div class="line">    }</div>
<div class="line">  }</div>
<div class="line">}</div>
</div><!-- fragment --><p>The above code is only an example to give an idea of how it can be done. It is not complete and only recognizes a few types. To make it useful it would have to be expanded to recognize all types, and perhaps add some generic way of converting an object to human readable string for printing.</p>
<p>For script objects that conversion can be done by enumerating the members of an object through the <a class="el" href="classas_i_script_object.html">asIScriptObject</a> interface.</p>
<p>The debugger may also need to be able to inspect the global variables that the functions access. As the global variables are stored in the module, there is the place to look for them. The <a class="el" href="classas_i_script_module.html">asIScriptModule</a> interface can be obtained by querying the module name from the function, and then getting the module pointer from the engine. Once the module is determined the global variables are enumerated much the same way as in the example above, except that the appropriate methods on the <a class="el" href="classas_i_script_module.html" title="The interface to the script modules.">asIScriptModule</a> interface are used instead.</p>
<h1><a class="anchor" id="doc_debug_4"></a>
Debugging internally executed scripts</h1>
<p>Some script execution is not initiated by the application, e.g. the initialization of global variables or the call to the script class destructor when destroying objects from the garbage collector. If these executions should be debugged, the application must set the context callback functions with a call to <a class="el" href="classas_i_script_engine.html#ae5ba9fe99b72c60392cdaeef164f2c65">asIScriptEngine::SetContextCallbacks</a>. The engine will invoke these callbacks to request a context from the application when it will execute a script internally. The application can then attach the debugger to the context it provides to the engine. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Sun Dec 18 2016 12:35:28 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.3.1 </li>
  </ul>
</div>
</body>
</html>
